Signal Document Reading and Writing

SE supports two file formats: NeXT's standard snd format, and its own native sig format. You can tell what format a file is in by looking at it with the NeXT Workspace Manager and noticing its file extension, for example, flute.snd or sitar.sig. 

SE editing is performed exclusively on sig documents. The structure of a signal document is what makes SE editing fast. See the section "More About Signal Documents" for details on their format.

Creating a New Document

You can create a new document in four ways:

1. By selecting New Document in the Document menu (or Command-n)
2. By selection New From NeXT File in the Document menu
3. By creating a new view window, or empty viewer, by selecting New Viewer Window from the Windows menu (command-N), and pasting in a selection from another document 
4. By dragging a NeXT snd file icon from the Workspace Manager into an empty viewer

When creating a new signal document from a NeXT snd file, recall that SE supports monophonic, 16-bit linear uncompressed samples with either a 22.05 or 44.1kHz sampling rates. The new signal document will have the same sample format as the snd file. Sample format conversion is not supported in release 0.9.

SE treats all new documents as temporary documents. That is, by default SE labels the new document as untitledn.sig (where n is an integer) in the /tmp directory. (In a moment we explain how to change this default location.) When you close the documents, SE will pop up an alert box to ask you if you want to delete the temporary untitled document or save it. 

In Release 0.9 it is not possible to rename an open document or save it under another name. The workaround for this, which applies only to new documents, is as follows:

1. Close the unsaved document. At this point SE asks you if you would like to save it. 
2. Choose the Save operation. Now SE gives you the opportunity to rename the file and save it in the directory of your choice. Note that if you click on Cancel in the Save panel, this cancels the save operation but not the previously issued close operation.

So in Release 0.9 a good strategy is to close and save under a new name immediately after you create a new document. Then simply open the document you just named and saved. You can, of course, rename non-open documents with the Workspace Manager at any time.

Setting the Default Directory for New Documents

In release 0.9, you can specify the default new document directory, or untitled directory, with a Unix shell command as follows:

	dwrite SignalEditor UntitledDirectory "new untitled directory"

(See the Unix documentation for more on the dwrite command.) Do this in a terminal window while SE is running. The next time that SE creates a new untitled document it will use the directory that you specify. By default, SE uses /tmp as the default new document directory.

Setting the Default Sampling Rate for New Documents

You can set the default sampling rate for new documents by means of the Unix shell command dwrite. Just type the following after you have opened SE:

	dwrite DefaultSamplingRate rate

where rate is either 22050 or 44100. (Note: don't add punctuation to these numbers, like 22.050 or 44,100.) The default sampling rate is only used when you create a new document with Command-n. If you create a document from a NeXT snd file, the snd file's sampling rate it used.

Opening a Signal Document

You can open an existing signal document by choosing Open from the Document menu (Command-o). SE presents you with an open panel. You may either directly type in the full file name, or use the panel's browser to find and double-click on the document. The open panel first looks in the directory where the current document resides. The current document is the document in the current document viewer window, indicated by a black or dark grey bar at the top of the window. If there is not a current document, SE looks in the user's home directory (if this is the beginning of a new session), or the last directory accessed in this session. 

*Note: If you try to open a document name that is a symbolic link to a signal document, SE warns you that it is going to use the real name of the document instead. 

Writing a Document

When you are done editing, SE can either save the signal document or write out a NeXT's snd file. Having the file in snd format means you can apply other NeXT sound tools to the file, or transfer it in the digital domain to another digital audio device.

To save a signal document select Save in the Document menu or type Command-s.

To write a signal document to an snd file select Write to NeXT File, in the Document menu.

To close a signal document, select Close in the Document menu.

*Note: There is no file-locking mechanism in SE. You should be careful when you have multiple SE applications running that edit the same document. The last save of the file may overwrite previous work done by someone else.

How SE Editing Works

Opening and editing signal documents is fast in SE because of the structure of the sig file format. It is important to realize that SE editing manipulates pointers only; it does not rearrange the order of the samples in their original signal documents on the disk. Imagine, for example, that you have opened five source documents that you intend to cut sections from them to create a new master document. Every time you cut and paste from a source into the master, the display of the master changes to reflect its new contents. SE plays the master document seamlessly, giving you the illusion that all of the samples have already been written to the master document. In actuality, SE is following pointers in the master and reading from the different source documents in order to play the master.

Foreign Samples in Save Operations

When you decide to save an edited master document, SE needs to make sure that any samples that have been inserted from a source document, or foreign document, are copied on disk into the master document. This is done because after you quit SE, you might delete, move, or change the name of the foreign document making it impossible for SE to access the foreign samples. When you save a master document containing foreign samples, SE guides you through a sequence of alert panels. You always have the choice to cancel the save.

A special situation can arise when the foreign samples are references in undone paste operations stored in the change stack (see the section on the change stack for more information). In this case, SE gives you the option to remove all undone operations from the change stack, leaving only the modifications which influence the current state of the document. Choosing to remove the undone change stack entries can greatly reduce the time and disk space necessary for saving a document.

Foreign Samples in Close Operations

Imagine that you have two documents open, document A and document B, and that Document B includes samples from document A. If you try to close document A, SE will alert you and give you a choice between cancelling the close or copying the samples from document A included in document B, into document B. If any samples from document A are references in undone change stack entries in document B, you can also opt to remove the undone entries from document B's change stack.

When you save a document (Command-s) that includes foreign samples, SE appends the foreign samples in the order in which they were pasted into the document. This allows SE to remove samples from a document if a paste is undone, keeping a document's disk usage to a minimum. In the above example, samples from document A had to be copied into document B because document A was closing. These samples might not have been appended onto document B in the optimum order, and SE might not be able to remove the samples from the document if the paste is undone, thus wasting disk space. It would have been a better idea to cancel the close, save document B, then close document A.

You will also be warned if the pasteboard contains any parts of a document being closed. You can either clear the pasteboard or cancel the close operation.